{"componentChunkName":"component---src-templates-post-js","path":"/blogs/opencode-cli-guide","result":{"data":{"markdownRemark":{"html":"

Introduction

\n

AI coding assistants have gone from novelty to necessity in just a couple of years. Tools like GitHub Copilot and Cursor showed developers what it feels like to have a second brain on tap — autocompleting functions, generating tests, and explaining unfamiliar code in plain English. But as the tooling matured, a new wave of developers started asking a different question: what if the AI didn't live inside an editor at all?

\n

That's where terminal-native AI tools come in. They run where your Git workflow already lives, understand your whole project rather than just the open file, and give you fine-grained control over how changes get applied. For many engineers — especially those who live in Vim, Neovim, or plain old bash — the terminal is home.

\n

Enter OpenCode CLI: an open-source, terminal-native AI coding agent designed for developers who want a powerful, transparent, and highly customizable AI pair programmer without being locked into a proprietary ecosystem. In this guide, we'll walk through everything you need to know — from installation to real-world workflows — and show you why it's quickly becoming a favorite among AI developer tools.

\n
\n

What is OpenCode CLI?

\n

OpenCode is an open-source AI coding agent that runs natively in your terminal. It's a single binary you launch with the opencode command, and it opens a polished terminal user interface (TUI) where you can chat with an AI model that has full access to your project.

\n

But calling it \"just a chatbot\" undersells it. OpenCode is an agent — it can read files, search your codebase, write and edit files, run commands, and work through multi-step tasks on your behalf. It's designed to feel like a thoughtful pair programmer sitting next to you, not a glorified autocomplete.

\n

The project's design philosophy is refreshingly pragmatic:

\n\n

While the terminal experience is the core, OpenCode also ships as a desktop app and an IDE extension, so you can pick the surface that fits your workflow.

\n
\n

Key Features

\n

Let's break down what makes OpenCode feel powerful in practice.

\n

AI-Powered Coding Assistance

\n

At its heart, OpenCode is a full agentic coding assistant. You can ask it to write features, fix bugs, refactor code, and explain complex logic — and it will actually do the work across your project, not just in a single file.

\n

Project-Aware Context

\n

OpenCode doesn't treat your files as isolated snippets. When you run /init, it analyzes your project and generates an AGENTS.md file in the root that captures the project's structure and coding patterns. Every future session reads that context, so the AI understands your conventions before it touches a single line.

\n
cd /path/to/project\nopencode\n/init
\n
\n

Tip: Commit your project's AGENTS.md file to Git. It helps OpenCode — and your teammates — understand the codebase instantly.

\n
\n

Terminal-Native Workflow

\n

Everything runs in your existing terminal emulator. There's no new IDE to learn, no cloud workspace to provision, and no context-switching. If you already live in a terminal, OpenCode feels instantly familiar.

\n

Plan Mode & Build Mode

\n

One of OpenCode's smartest features is the ability to separate thinking from doing. Press Tab to switch into Plan mode, describe the feature you want, and the agent will propose an implementation strategy without changing any files. Review it, iterate on it, then press Tab again to enter Build mode and let it execute.

\n
When a user deletes a note, we'd like to flag it as deleted in the database.\nThen create a screen that shows all the recently deleted notes.
\n

Multi-File Editing

\n

Ask OpenCode to implement a feature that spans several files, and it will make coordinated edits across all of them — updating imports, touching related modules, and keeping the change consistent.

\n

Undo / Redo

\n

Made a change you don't like? Run /undo to revert it, and OpenCode brings back your original prompt so you can tweak and retry. Run it multiple times to step backward through several changes, or use /redo to move forward again.

\n

Git Integration

\n

OpenCode works naturally alongside Git. It can operate on PR branches (opencode pr <number>), and the GitHub agent lets you automate repository workflows like issue triage and review through a GitHub Actions workflow.

\n

Support for Multiple LLM Providers

\n

This is a defining differentiator. OpenCode builds on the AI SDK and Models.dev, giving you access to 75+ LLM providers. You can switch brains for different tasks — a fast model for quick questions, a frontier model for deep refactors — all from the same interface.

\n

Fast Performance

\n

OpenCode is a compiled binary with a snappy TUI. Startup is quick, keystrokes are responsive, and sessions are cached so you can resume where you left off instantly.

\n

Extensibility

\n

OpenCode is built to be extended:

\n\n

Custom Prompts & Commands

\n

Create your own reusable slash commands and prompts so common workflows are one keystroke away.

\n

Permissions & Safety

\n

OpenCode runs with a permission system that lets you gate what the agent can do — read-only vs. write access, allowed tools, and command execution. Combined with Plan mode and /undo, you stay in control.

\n
\n

Installation

\n

OpenCode is easy to install on every major platform.

\n

One-Line Install Script

\n

The fastest way:

\n
curl -fsSL https://opencode.ai/install | bash
\n

Using a Package Manager

\n

npm / Bun / pnpm / Yarn:

\n
npm install -g opencode-ai\nbun install -g opencode-ai\npnpm install -g opencode-ai\nyarn global add opencode-ai
\n

Homebrew (macOS and Linux):

\n
brew install anomalyco/tap/opencode
\n
\n

Note: The OpenCode tap is updated more frequently than the official Homebrew formula, so the tap is recommended.

\n
\n

Arch Linux:

\n
sudo pacman -S opencode        # Stable\nparu -S opencode-bin           # Latest from AUR
\n

Windows:

\n

The best experience on Windows is through WSL (Windows Subsystem for Linux), but you also have several native options:

\n
choco install opencode          # Chocolatey\nscoop install opencode          # Scoop\nnpm install -g opencode-ai      # npm\nmise use -g github:anomalyco/opencode  # mise\ndocker run -it --rm ghcr.io/anomalyco/opencode  # Docker
\n

You can also grab prebuilt binaries directly from the GitHub Releases page.

\n
\n

Getting Started

\n

Let's take OpenCode for a spin.

\n

1. Configure a provider

\n

Run the /connect command inside the TUI and choose your provider. If you're new, the easiest starting point is OpenCode Zen — a curated list of models tested and verified by the OpenCode team.

\n
/connect
\n

Pick a provider, and it will guide you through authentication — either pasting an API key or opening a browser to sign in.

\n
\n

Note: If you already have a ChatGPT Plus, GitHub Copilot, or GitLab Duo subscription, OpenCode can use those credentials directly with zero extra setup.

\n
\n

2. Select a model

\n

List available models with:

\n
/models
\n

Models appear in provider/model format (for example, anthropic/claude-sonnet-4). You can switch models at any time.

\n

3. Open your project

\n

Navigate to your project and launch OpenCode:

\n
cd /path/to/project\nopencode
\n

Run /init so the agent builds an AGENTS.md with project context.

\n

4. Ask questions

\n

You can ask OpenCode to explain parts of the codebase you didn't write. Use @ to fuzzy-search for files:

\n
How is authentication handled in @packages/functions/src/api/index.ts
\n

5. Make changes

\n

For a direct change, just describe it:

\n
We need to add authentication to the /settings route. Take a look at how this is\nhandled in the /notes route and implement the same logic for /settings.
\n

For anything non-trivial, switch to Plan mode first (press Tab), review the plan, then switch back to Build mode and say \"Go ahead and make the changes.\"

\n

6. Undo if needed

\n

Not happy with the result?

\n
/undo
\n

OpenCode reverts the changes and brings back your prompt so you can refine it.

\n

7. Non-interactive mode

\n

You don't always need the full TUI. For quick questions or scripting:

\n
opencode run \"Explain how closures work in JavaScript\"
\n

This runs OpenCode headlessly and prints the answer — perfect for automation and CI pipelines.

\n
\n

Real-World Use Cases

\n

Here's where OpenCode shines in day-to-day development.

\n

Debugging

\n

Stuck on a cryptic error? Paste the stack trace and let the agent trace the root cause:

\n
opencode run \"The tests are failing with a TypeScript type error in src/services. Diagnose the issue and propose a fix.\"
\n

Refactoring Legacy Code

\n

OpenCode can safely modernize old code across a codebase, preserving behavior while improving structure. Run it in Plan mode first to review exactly what will change before committing.

\n

Explaining Unfamiliar Code

\n

Joining a new codebase is intimidating. Ask targeted questions about specific files, and OpenCode explains the architecture using your project's actual code as context.

\n

Writing Tests

\n

Generate unit and integration tests that match your existing test conventions:

\n
Look at the testing patterns in @tests/unit and write equivalent tests for the new payment service.
\n

Documentation Generation

\n

Struggling to keep docs current? OpenCode can generate README sections, inline doc comments, and API documentation straight from your source.

\n

Code Review

\n

Use opencode pr <number> to fetch a PR branch and have the agent review the diff for bugs, edge cases, and style issues before you request human review.

\n

Learning New Frameworks

\n

Ask OpenCode to translate a pattern you know into a framework you don't:

\n
I know how to do dependency injection in Spring. Show me how to do the same in FastAPI, using this project's conventions.
\n
\n

Supported AI Models

\n

One of OpenCode's biggest advantages is provider freedom. Because it's built on the AI SDK and Models.dev, it supports 75+ providers, including:

\n

Hosted Providers

\n\n

Local Models

\n

Prefer to keep everything on your machine? OpenCode works with:

\n\n

Local models mean zero per-token cost, full privacy, and the freedom to experiment offline.

\n

OpenCode's Own Offerings

\n\n
\n

Advantages

\n

Why choose OpenCode over a traditional, editor-bound assistant?

\n

Privacy

\n

Your code and prompts are sent only to the provider you explicitly configure. There's no opaque middleman collecting your data by default.

\n

Speed

\n

As a native terminal binary, OpenCode is fast to launch and responsive. No bloated IDE extensions or remote workspace round-trips.

\n

Open-Source Ecosystem

\n

Being open source means total transparency and the ability to contribute. If you don't like a behavior, you can change it — or install a community plugin that does.

\n

Flexibility

\n

Switch between 75+ providers and local models with a single command. Use the best model for each task, not whatever the tool vendor decided to bundle.

\n

Cost Efficiency

\n

Because you control the provider, you control the bill. Use cheap models for routine tasks, frontier models only when needed, or run fully local models for $0.

\n

No Vendor Lock-In

\n

The TUI and config are provider-agnostic. If a new model provider launches tomorrow, you just add a key — no migration.

\n

Local Model Support

\n

For air-gapped environments, privacy-sensitive work, or budget constraints, local models through Ollama, LM Studio, or llama.cpp are a first-class option.

\n
\n

Comparison

\n

How does OpenCode stack up against the other major terminal AI assistants?

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
FeatureOpenCode CLIClaude CodeOpenAI Codex CLIGemini CLI
Open source✅ Yes❌ No (proprietary)✅ Yes❌ No
Terminal-first✅ Yes✅ Yes✅ Yes✅ Yes
Local model support✅ Yes (Ollama, LM Studio, llama.cpp)❌ No❌ No❌ No
Multiple providers✅ 75+ providers⚠️ Limited (Anthropic-centric)❌ OpenAI-centric❌ Google-centric
Customization✅ High (plugins, MCP, custom agents, themes)⚠️ Medium (extends Claude)⚠️ Medium⚠️ Low-Medium
Pricing✅ Free (bring your own provider)⚠️ Subscription/usage⚠️ Usage-based⚠️ Free tier + usage
Ease of use✅ Great onboarding (/connect, /init)✅ Very good✅ Good✅ Good
\n

The takeaway: if you want freedom of choice — open source, any provider, and local models — OpenCode is the strongest option today. Claude Code and the others are polished tools, but they're tightly coupled to their parent companies' ecosystems.

\n
\n

Tips and Best Practices

\n

A few habits that get the most out of OpenCode:

\n
    \n
  1. Commit AGENTS.md. Project context is the single biggest quality lever. Keep it up to date.
    2. \n
  2. Use Plan mode for big changes. Always let it propose a strategy before touching code. Iterate on the plan first.
    3. \n
  3. Be specific in prompts. Talk to OpenCode like a junior engineer: give file paths, expected behavior, and constraints.
    4. \n
  4. Use @ to reference files. Fuzzy-search with @ gives the agent precise file context.
    5. \n
  5. Lean on /undo. Don't be afraid to experiment — you can always revert.
    6. \n
  6. Try opencode run for automation. Script common questions or wire it into CI for quick answers.
    7. \n
  7. Match the model to the task. Use fast/cheap models for routine edits, frontier models for hard refactors.
    8. \n
  8. Configure permissions. Start read-only where possible, then open up write access as you build trust.
    9. \n
  9. Use MCP servers and plugins. Extend OpenCode with your team's tools instead of reinventing workflows.
    10. \n
  10. Share sessions with /share when collaborating, so teammates can see exactly what the agent did.
    11. \n
\n
\n

Limitations

\n

No tool is perfect, and it's worth being honest about OpenCode's current rough edges:

\n\n

These are fair trade-offs for the flexibility you get, and most are actively being addressed by the project's rapid development.

\n
\n

Future of AI Terminal Assistants

\n

We're at an inflection point. The next wave of developer tooling isn't about autocomplete — it's about agents that plan, execute, and verify multi-step work. Terminal-native assistants like OpenCode are at the center of that shift.

\n

Several trends point to where this is heading:

\n\n

OpenCode is well-positioned in this ecosystem: it's open source, provider-agnostic, and aggressively extensible. As agentic workflows become the default, tools that let you choose the brain — and take it with you anywhere — will win the developer's trust.

\n
\n

Conclusion

\n

OpenCode CLI is more than just another AI coding assistant. It's a terminal-native, open-source agent that puts you in control: your provider, your models, your permissions, your workflow. Whether you're a solo developer who wants a powerful pair programmer, an engineer who values privacy and local models, or a team building custom agentic workflows, OpenCode adapts to you — not the other way around.

\n

The fastest way to decide if it's for you is to try it:

\n
curl -fsSL https://opencode.ai/install | bash
\n

Then cd into a project, run opencode, hit /connect, and ask it something about your code. Five minutes in, you'll know exactly why terminal-native AI tools are the future — and why OpenCode CLI deserves a permanent spot in your toolkit.

","frontmatter":{"title":"OpenCode CLI: Your Terminal-Native AI Coding Assistant","description":"A comprehensive guide to OpenCode CLI — the open-source, terminal-native AI coding agent. Learn installation, features, supported providers, use cases, and how it compares with Claude Code, Codex, and Gemini CLI.","date":"2026-07-30","slug":"/blogs/opencode-cli-guide","tags":["AI","Developer Tools","CLI","Open Source","Tutorial"]}},"allMarkdownRemark":{"edges":[{"node":{"frontmatter":{"title":"OpenCode CLI: Your Terminal-Native AI Coding Assistant","description":"A comprehensive guide to OpenCode CLI — the open-source, terminal-native AI coding agent. Learn installation, features, supported providers, use cases, and how it compares with Claude Code, Codex, and Gemini CLI.","slug":"/blogs/opencode-cli-guide","tags":["AI","Developer Tools","CLI","Open Source","Tutorial"]}}}]}},"pageContext":{}}}